/**
  * @page	libraries	Writing Libraries
  * @ingroup guidedev
  * @author	Bastian Blywis

<p>The ScatterWeb firmware can be easily extended by libraries.</p>

<p>Some general rules:</p>
<ul>
	<li>Write a library if the included source code is an optional component and/or a complete module on its own, e.g. a driver (see \ref driver).</li>
	<li>Do not expose "private" members (functions or variables). Use the keyword <tt>static</tt> if possible</li> to adjust the scope.
	<li>Document your code as usual, but put your focus especially on the "public" member.</li>
	<li>Only a thoughtful developed interface keeps your code useful for other people.</li>
</ul>

<p>A library basically consists of the following parts:
	<ol>
		<li>\ref libraries_makefile with name, description and dependencies</li>
		<li>\ref libraries_compiletime</li>
		<li>\ref libraries_documentation</li>
		<li>A \ref libraries_public</li>
		<li>\ref libraries_source file(-s)</li>
		<li>\ref libraries_private</li>
	</ol>
	A typical source tree therefore looks like this:
<pre>@verbatim
	LIBRARY_ROOT/makefile
	LIBRARY_ROOT/libLIBRARY_NAME.h
	LIBRARY_ROOT/doc/libLIBRARY_NAME.doc.html
	LIBRARY_ROOT/include/ScatterWeb.LIBRARY_NAME.h
	LIBRARY_ROOT/src/ScatterWeb.LIBRARY_NAME.c
	LIBRARY_ROOT/src/ScatterWeb.LIBRARY_NAME.internals.h
@endverbatim</pre>
	You can use the provided EMPTY library as template.
</p>

<p>Please read the section \ref docs.</p>

@section	libraries_makefile	Libray Makefile
<p>The makefile is vital to the build process. Choose a descriptive <i>name</i> containing no whitespaces or special characters. The <i>description</i> should be no longer than a single line. List the names of any library this one <i>depends</i> on (without the lib-prefix).</p>
<p>Example:</p>
<pre>@verbatim
#
# Configure this makefile here:
#
NAME			:= LIBRARY_NAME
DESCRIPTION		:= This is a description of library LIBRARY_NAME
DEPENDS			:= DEPENDING_ON_THIS_LIBRARY

###############################################################################
SYSROOT := ../..
include $(SYSROOT)/System/makefile.library
@endverbatim</pre>

@section	libraries_compiletime	Compile Time Options
<p>Store compile time options in this file.</p>
<p>The options of all libraries will be aggregated in the group \ref config_compile and are therefore listed at a central location.</p>
<p>Example:</p>
<pre>@verbatim
/**
 * @file		libLIBRARY_NAME.h
 * @brief		Default compile-time configuration of library LIBRARY_NAME
 * @ingroup	config_compile, LIBRARY_NAME
 * @since		0.1
 * @version	$Rev$
 *
 */

/**
 * @addtogroup	config_compile
 * @{
 */

#define SOME_OPTION 4

#ifndef IMPORTANT_STRING
#define IMPORTANT_STRING FooBar
#endif

///@}
@endverbatim</pre>

@section	libraries_documentation	Documentation
<p>The content of this file gets the introduction of the library documentation.</p>
<p>Example:</p>
<pre>@verbatim
/**
 * @defgroup	libLIBRARY_NAME LIBRARY_NAME
 * @ingroup	driver

\p Library LIBRARY_NAME is a vital part of this project and a state of the art implementation. Do 
not question its beauty!

\p Since this library is beta and still in development you can contact
the author directly if you are quite sure that you found a bug. For
general questions please use the mailing list or consult the ScatterWeb
website:
http://scatterweb.mi.fu-berlin.de and the mailinglist
scatterweb@lists.spline.inf.fu-berlin.de (subscription via the Website).

*/
@endverbatim</pre>

@section	libraries_public	Public Interface
<p>The public interface lets other people use your library.</p>
<p>A initialization function should usually be included.</p>
<p>Example:</p>
<pre>@verbatim
/**
 * @file		ScatterWeb.LIBRARY_NAME.h
 * @ingroup	libLIBRARY_NAME
 * @brief		LIBRARY_NAME library, Public interface
 * 
 * @author	Someone	<someone@some.where>
 * @date		Aug 2007
 * @since		1.1
 * @version	$Rev$
 */

/**
 * @ingroup	libLIBRARY_NAME
 * @{
 */

#ifndef __LIBRARY_NAME_H__
#define __LIBRARY_NAME_H__

/******************************************************************************
 * @name	 initialisation and usage
 * @{
 */

/**
* @brief Initialize LIBRARY_NAME
*
*/
void LIBRARY_NAME_init();

#endif /*__LIBRARY_NAME_H__*/
/** @} */
@endverbatim</pre>

@section	libraries_source	Source Code
<p>Your source code may consist of one or more file(-s) but you should name the main file including the initialization function in ScatterWeb.LIBRARY_NAME.c.</p>
<p>Example:</p>
<pre>@verbatim
/**
 * @file		ScatterWeb.LIBRARY_NAME.c
 * @ingroup	libLIBRARY_NAME
 * @brief		LIBRARY_NAME library
 * 
 * @author	Someone	<someone@some.where>
 * @date		Aug 2007
 * @since		1.1
 * @version	$Rev$
 * 
 */

#include "ScatterWeb.LIBRARY_NAME.internals.h"
#include "ScatterWeb.LIBRARY_NAME.h"

/******************************************************************************
 * @name	Initialization and configuration
 * @{
 */

void LIBRARY_NAME_init() {
#warning library LIBRARY_NAME does nothing and is useless
}

/** @} */

@endverbatim</pre>

@section	libraries_private	Private Definitions
<p>Keep private member definitions out of the headers file(-s) in the <tt>include</tt> directory. Place them in one or more seperate headers in the <tt>src</tt> path.</p>
<p>Use <tt>static</tt> whenever if applicable.</p>
<p>Example:</p>
<pre>@verbatim
/**
 * @file		ScatterWeb.LIBRARY_NAME.internals.h
 * @ingroup	libLIBRARY_NAME
 * @brief		LIBRARY_NAME library
 * 
 * @author	Someone	<someone@some.where>
 * @date		Aug 2007
 * @since		1.1
 * @version	$Rev$
 * 
 * Header file containing private declarations used by the LIBRARY_NAME library.
 */

#ifndef LIBRARY_NAME_INT_H_
#define LIBRARY_NAME_INT_H_

#include <ScatterWeb.System.h>

void superSecretFunction();

#endif /*LIBRARY_NAME_INT_H_*/
@endverbatim</pre>

*/ 